Opening a Pipe

USBOpenPipe

The USBOpenPipe function verifies that a specified device has the specified endpoint and then sets up a connection to that endpoint. It also determines the type of endpoint (control, isochronous, interrupt, or bulk). A reference ( USBPipeRef ) to this connection is returned. This reference is passed to the USB on all subsequent data transactions for this pipe. See the USB Transaction Functions for information about performing data transactions.

OSStatus USBOpenPipe(USBPB *pb);

Required fields in the USBPB parameter block for the USBOpenPipe function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

<--> usbReference

--> Device reference of device to be opened <-- Reference to the pipe opened

--> usbClassType

Type of endpoint ( kUSBBulk, kUSBInterrupt, kUSBIsoc )

--> usbOther

The endpoint number within the device to open a pipe to, the endpoint number from the endpoint descriptor

--> usbWValue

maxPacketSize

--> usbFlags

Indicates whether the direction of the endpoint to be opened is in or out ( kUSBIn, kUSBOut )

USBClosePipeByReference

The USBClosePipeByReference function closes the specified pipe currently opened. The pipe reference is deleted and no further reference can be made to it. All outstanding transactions on the specified pipe are returned with a kUSBAborted status.

OSStatus USBClosePipeByReference(USBPipeRef ref);

--> ref

Pipe reference for the pipe to close

The USBClosePipeByReference function is similar to the pipe state control functions described later in this document. This function does not require a parameter block and does not complete asynchronously.

See also the USBFindNextPipe and USBOpenPipe functions.

The errors returned by the USBClosePipeByReference function include:

kUSBUnknownPipeErr

-6997

pipe reference not recognized

The kUSBPipeStalledErr and kUSBPipeIdleErr are also returned if the pipe is not currently active. In this instance, the call has failed and the pipe will have to be activated again before it can be closed. This behavior will be changed to return noErr and succeed in a later release of the USB software.

kUSBPipeStalledErr	-6979	pipe is stalled, pipe not closed
kUSBPipeIdleErr	-6980	pipe is idle, pipe not closed

USBGetConfigurationDescriptor

The USBGetConfigurationDescriptor function gives class drivers access to the USB configuration descriptor.

The USBGetConfigurationDescriptor function returns configuration descriptors that define the contents of the configuration data for the device. The configuration descriptor is 9 bytes, and is followed by all the interface descriptors complete with their associated endpoint descriptors as well as any class or vendor specific descriptors. The USBGetConfigurationDescriptor function returns as much of this data for one configuration as requested.

OSStatus USBGetConfigurationDescriptor(USBPB *pb);

Required fields in the USBPB parameter block for the USBGetConfigurationDescriptor function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

--> usbReference

Device reference

--> usbWValue

Configuration number

--> usbReqCount

Amount of configuration data requested

--> usbBuffer

--> Pointer to the address to store the data in

<-- usbActCount

Actual amount of data returned

--> usbFlags

Should be set to 0

The USBGetConfigurationDescriptor function differs from the USBGetFullConfigurationDescriptor function in that it allows the calling driver to specify how much configuration data the function should return. USBGetConfigurationDescriptor allows the caller to get either the 9-byte configuration descriptor ( USBConfigurationDescriptor ), a descriptor specified in usbWValue, or as much of the configuration data as requested.

The USBGetConfigurationDescriptor function requires the caller to allocate the memory for the returned data and pass a pointer to the address of the allocated memory block in usbBuffer . The caller must also specify how many bytes of the configuration data to return to the buffer in the usbReqCount field.

The usbReqCount field specifies the largest amount of data that you want returned. If the descriptor has less data, less data is returned. If the descriptor has more data, only the requested amount of data is returned. This is not an error condition.